Top

odfdo.variable module

# Copyright 2018 Jérôme Dumonteil
# Copyright (c) 2009-2013 Ars Aperta, Itaapy, Pierlis, Talend.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
#
# Authors (odfdo project): jerome.dumonteil@gmail.com
# The odfdo project is a derivative work of the lpod-python project:
# https://github.com/lpod/lpod-python
# Authors: Hervé Cauwelier <herve@itaapy.com>
#          Jerome Dumonteil <jerome.dumonteil@itaapy.com>

from .datatype import Date, DateTime, Duration
from .const import ODF_META
from .utils import _set_value_and_type
from .element import Element, register_element_class


class VarDecls(Element):
    _tag = 'text:variable-decls'


class VarDecl(Element):
    _tag = 'text:variable-decl'
    _properties = (('name', 'text:name'), ('value_type', 'office:value-type'))

    def __init__(self, name=None, value_type=None, **kw):
        super().__init__(**kw)
        if self._do_init:
            if name:
                self.name = name
            if value_type:
                self.value_type = value_type


VarDecl._define_attribut_property()


class VarSet(Element):
    _tag = 'text:variable-set'
    _properties = (('name', 'text:name'), ('style', 'style:data-style-name'),
                   ('display', 'text:display'))

    def __init__(self,
                 name=None,
                 value=None,
                 value_type=None,
                 display=False,
                 text=None,
                 style=None,
                 **kw):
        super().__init__(**kw)
        if self._do_init:
            if name:
                self.name = name
            if style:
                self.style = style
            text = _set_value_and_type(
                self, value=value, value_type=value_type, text=text)
            if not display:
                self.display = 'none'
            else:
                self.text = text


VarSet._define_attribut_property()


class VarGet(Element):
    _tag = 'text:variable-get'
    _properties = (('name', 'text:name'), ('style', 'style:data-style-name'))

    def __init__(self,
                 name=None,
                 value=None,
                 value_type=None,
                 text=None,
                 style=None,
                 **kw):
        super().__init__(**kw)
        if self._do_init:
            if name:
                self.name = name
            if style:
                self.style = style
            text = _set_value_and_type(
                self, value=value, value_type=value_type, text=text)
            self.text = text


VarGet._define_attribut_property()


class UserFieldDecls(Element):
    _tag = 'text:user-field-decls'


class UserFieldDecl(Element):
    _tag = 'text:user-field-decl'
    _properties = (('name', 'text:name'), )

    def __init__(self, name=None, value=None, value_type=None, **kw):
        super().__init__(**kw)
        if self._do_init:
            if name:
                self.name = name
            _set_value_and_type(self, value=value, value_type=value_type)


UserFieldDecl._define_attribut_property()


class UserFieldGet(Element):
    _tag = 'text:user-field-get'
    _properties = (('name', 'text:name'), ('style', 'style:data-style-name'))

    def __init__(self,
                 name=None,
                 value=None,
                 value_type=None,
                 text=None,
                 style=None,
                 **kw):
        super().__init__(**kw)
        if self._do_init:
            if name:
                self.name = name
            text = _set_value_and_type(
                self, value=value, value_type=value_type, text=text)
            self.text = text
            if style:
                self.style = style


UserFieldGet._define_attribut_property()


class UserFieldInput(UserFieldGet):
    _tag = 'text:user-field-input'


UserFieldInput._define_attribut_property()


class UserDefined(Element):
    """Return a user defined field <text:user-defined>. If the current
    document is provided, try to extract the content of the meta user defined
    field of same name.

    Arguments:

        name -- str, name of the user defined field

        value -- python typed value, value of the field

        value_type -- str, office:value-type known type

        text -- str

        style -- str

        from_document -- ODF document
    """
    _tag = 'text:user-defined'
    _properties = (('name', 'text:name'), ('style', 'style:data-style-name'))

    def __init__(self,
                 name=None,
                 value=None,
                 value_type=None,
                 text=None,
                 style=None,
                 from_document=None,
                 **kw):
        super().__init__(**kw)
        if self._do_init:
            if name:
                self.name = name
            if style:
                self.style = style
            if from_document is not None:
                meta_infos = from_document.get_part(ODF_META)
                if meta_infos is not None:
                    content = meta_infos.get_user_defined_metadata_of_name(
                        name)
                    if content is not None:
                        value = content.get('value', None)
                        value_type = content.get('value_type', None)
                        text = content.get('text', None)
            text = _set_value_and_type(
                self, value=value, value_type=value_type, text=text)
            self.text = text


UserDefined._define_attribut_property()


class VarPageNumber(Element):
    """
    select_page -- string in ('previous', 'current', 'next')

    page_adjust -- int (to add or subtract to the page number)
    """
    _tag = 'text:page-number'
    _properties = (('select_page', 'text:select-page'), ('page_adjust',
                                                         'text:page-adjust'))

    def __init__(self, select_page=None, page_adjust=None, **kw):
        super().__init__(**kw)
        if self._do_init:
            if select_page is None:
                select_page = 'current'
            self.select_page = select_page
            if page_adjust is not None:
                self.page_adjust = page_adjust


VarPageNumber._define_attribut_property()


class VarPageCount(Element):
    _tag = 'text:page-count'


class VarDate(Element):
    _tag = 'text:date'
    _properties = (('date', 'text:date-value'), ('fixed', 'text:fixed'),
                   ('data_style', 'style:data-style-name'),
                   ('date_adjust', 'text:date-adjust'))

    def __init__(self,
                 date=None,
                 fixed=False,
                 data_style=None,
                 text=None,
                 date_adjust=None,
                 **kw):
        super().__init__(**kw)
        if self._do_init:
            self.date = DateTime.encode(date)
            if fixed:
                self.fixed = True
            if data_style is not None:
                self.data_style = data_style
            if text is None:
                text = Date.encode(date)
            self.text = text
            if date_adjust is not None:
                self.date_adjust = Duration.encode(date_adjust)


VarDate._define_attribut_property()


class VarTime(Element):
    _tag = 'text:time'
    _properties = (('time', 'text:time-value'), ('fixed', 'text:fixed'),
                   ('data_style', 'style:data-style-name'),
                   ('time_adjust', 'text:time-adjust'))

    def __init__(self,
                 time=None,
                 fixed=False,
                 data_style=None,
                 text=None,
                 time_adjust=None,
                 **kw):
        super().__init__(**kw)
        if self._do_init:
            self.time = DateTime.encode(time)
            if fixed:
                self.fixed = True
            if data_style is not None:
                self.data_style = data_style
            if text is None:
                text = time.strftime('%H:%M:%S')
            self.text = text
            if time_adjust is not None:
                self.date_adjust = Duration.encode(time_adjust)


VarTime._define_attribut_property()


class VarChapter(Element):
    _tag = 'text:chapter'
    _properties = (('display', 'text:display'), ('outline_level',
                                                 'text:outline-level'))
    display_value_choice = {
        'number', 'name', 'number-and-name', 'plain-number',
        'plain-number-and-name'
    }

    def __init__(self, display='name', outline_level=None, **kw):
        """display can be: 'number', 'name', 'number-and-name', 'plain-number' or
                           'plain-number-and-name'
        """
        super().__init__(**kw)
        if self._do_init:
            if display not in VarChapter.display_value_choice:
                raise ValueError("unknown display value: %s" % display)
            self.display = display
            if outline_level is not None:
                self.outline_level = outline_level


VarChapter._define_attribut_property()


class VarFileName(Element):
    _tag = 'text:file-name'
    _properties = (('display', 'text:display'), ('fixed', 'text:fixed'))
    display_value_choice = {'full', 'path', 'name', 'name-and-extension'}

    def __init__(self, display='full', fixed=False, **kw):
        """display can be: 'full', 'path', 'name' or 'name-and-extension'
        """
        super().__init__(**kw)
        if self._do_init:
            if display not in VarFileName.display_value_choice:
                raise ValueError("unknown display value: %s" % display)
            self.display = display
            if fixed:
                self.fixed = True


VarFileName._define_attribut_property()


class VarInitialCreator(Element):
    _tag = 'text:initial-creator'
    _properties = (('fixed', 'text:fixed'), )

    def __init__(self, fixed=False, **kw):
        super().__init__(**kw)
        if self._do_init:
            if fixed:
                self.fixed = True


VarInitialCreator._define_attribut_property()


class VarCreationDate(Element):
    _tag = 'text:creation-date'
    _properties = (('fixed', 'text:fixed'), ('data_style',
                                             'style:data-style-name'))

    def __init__(self, fixed=False, data_style=None, **kw):
        super().__init__(**kw)
        if self._do_init:
            if fixed:
                self.fixed = True
            if data_style:
                self.data_style = data_style


VarCreationDate._define_attribut_property()


class VarCreationTime(Element):
    _tag = 'text:creation-time'
    _properties = (('fixed', 'text:fixed'), ('data_style',
                                             'style:data-style-name'))

    def __init__(self, fixed=False, data_style=None, **kw):
        super().__init__(**kw)
        if self._do_init:
            if fixed:
                self.fixed = True
            if data_style:
                self.data_style = data_style


VarCreationTime._define_attribut_property()


class VarDescription(VarInitialCreator):
    _tag = 'text:description'


VarDescription._define_attribut_property()


class VarTitle(VarInitialCreator):
    _tag = 'text:title'


VarTitle._define_attribut_property()


class VarSubject(VarInitialCreator):
    _tag = 'text:subject'


VarSubject._define_attribut_property()


class VarKeywords(VarInitialCreator):
    _tag = 'text:keywords'


VarKeywords._define_attribut_property()

register_element_class(VarDecls)
register_element_class(VarDecl)
register_element_class(VarSet)
register_element_class(VarGet)
register_element_class(UserFieldDecls)
register_element_class(UserFieldDecl)
register_element_class(UserFieldGet)
register_element_class(UserFieldInput)
register_element_class(UserDefined)
register_element_class(VarPageNumber)
register_element_class(VarPageCount)
register_element_class(VarDate)
register_element_class(VarTime)
register_element_class(VarChapter)
register_element_class(VarFileName)
register_element_class(VarInitialCreator)
register_element_class(VarCreationDate)
register_element_class(VarCreationTime)
register_element_class(VarDescription)
register_element_class(VarTitle)
register_element_class(VarSubject)
register_element_class(VarKeywords)

Module variables

var ODF_META

Classes

class UserDefined

Return a user defined field . If the current document is provided, try to extract the content of the meta user defined field of same name.

Arguments:

name -- str, name of the user defined field

value -- python typed value, value of the field

value_type -- str, office:value-type known type

text -- str

style -- str

from_document -- ODF document
class UserDefined(Element):
    """Return a user defined field <text:user-defined>. If the current
    document is provided, try to extract the content of the meta user defined
    field of same name.

    Arguments:

        name -- str, name of the user defined field

        value -- python typed value, value of the field

        value_type -- str, office:value-type known type

        text -- str

        style -- str

        from_document -- ODF document
    """
    _tag = 'text:user-defined'
    _properties = (('name', 'text:name'), ('style', 'style:data-style-name'))

    def __init__(self,
                 name=None,
                 value=None,
                 value_type=None,
                 text=None,
                 style=None,
                 from_document=None,
                 **kw):
        super().__init__(**kw)
        if self._do_init:
            if name:
                self.name = name
            if style:
                self.style = style
            if from_document is not None:
                meta_infos = from_document.get_part(ODF_META)
                if meta_infos is not None:
                    content = meta_infos.get_user_defined_metadata_of_name(
                        name)
                    if content is not None:
                        value = content.get('value', None)
                        value_type = content.get('value_type', None)
                        text = content.get('text', None)
            text = _set_value_and_type(
                self, value=value, value_type=value_type, text=text)
            self.text = text

Ancestors (in MRO)

Static methods

def __init__(

self, name=None, value=None, value_type=None, text=None, style=None, from_document=None, **kw)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self,
             name=None,
             value=None,
             value_type=None,
             text=None,
             style=None,
             from_document=None,
             **kw):
    super().__init__(**kw)
    if self._do_init:
        if name:
            self.name = name
        if style:
            self.style = style
        if from_document is not None:
            meta_infos = from_document.get_part(ODF_META)
            if meta_infos is not None:
                content = meta_infos.get_user_defined_metadata_of_name(
                    name)
                if content is not None:
                    value = content.get('value', None)
                    value_type = content.get('value_type', None)
                    text = content.get('text', None)
        text = _set_value_and_type(
            self, value=value, value_type=value_type, text=text)
        self.text = text

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

var children

var clone

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var name

Get /set the attribute text:name

var parent

var root

var style

Get /set the attribute style:data-style-name

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class UserFieldDecl

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class UserFieldDecl(Element):
    _tag = 'text:user-field-decl'
    _properties = (('name', 'text:name'), )

    def __init__(self, name=None, value=None, value_type=None, **kw):
        super().__init__(**kw)
        if self._do_init:
            if name:
                self.name = name
            _set_value_and_type(self, value=value, value_type=value_type)

Ancestors (in MRO)

Static methods

def __init__(

self, name=None, value=None, value_type=None, **kw)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self, name=None, value=None, value_type=None, **kw):
    super().__init__(**kw)
    if self._do_init:
        if name:
            self.name = name
        _set_value_and_type(self, value=value, value_type=value_type)

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

var children

var clone

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var name

Get /set the attribute text:name

var parent

var root

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class UserFieldDecls

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class UserFieldDecls(Element):
    _tag = 'text:user-field-decls'

Ancestors (in MRO)

Static methods

def __init__(

self, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self, **kwargs):
    tag_or_elem = kwargs.pop('tag_or_elem', None)
    if tag_or_elem is None:
        # Instance for newly created object: create new lxml element and
        # continue by subclass __init__
        # If the tag key word exists, make a custom element
        self._do_init = True
        tag = kwargs.pop('tag', self._tag)
        self.__element = self.make_etree_element(tag)
    else:
        # called with an existing lxml element, sould be a result of
        # from_tag() casting, do not execute the subclass __ini__
        if not isinstance(tag_or_elem, _Element):
            raise TypeError(
                '"%s" is not an element node' % type(tag_or_elem))
        self._do_init = False
        self.__element = tag_or_elem

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

var children

var clone

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var parent

var root

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class UserFieldGet

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class UserFieldGet(Element):
    _tag = 'text:user-field-get'
    _properties = (('name', 'text:name'), ('style', 'style:data-style-name'))

    def __init__(self,
                 name=None,
                 value=None,
                 value_type=None,
                 text=None,
                 style=None,
                 **kw):
        super().__init__(**kw)
        if self._do_init:
            if name:
                self.name = name
            text = _set_value_and_type(
                self, value=value, value_type=value_type, text=text)
            self.text = text
            if style:
                self.style = style

Ancestors (in MRO)

Static methods

def __init__(

self, name=None, value=None, value_type=None, text=None, style=None, **kw)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self,
             name=None,
             value=None,
             value_type=None,
             text=None,
             style=None,
             **kw):
    super().__init__(**kw)
    if self._do_init:
        if name:
            self.name = name
        text = _set_value_and_type(
            self, value=value, value_type=value_type, text=text)
        self.text = text
        if style:
            self.style = style

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

var children

var clone

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var name

Get /set the attribute text:name

var parent

var root

var style

Get /set the attribute style:data-style-name

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class UserFieldInput

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class UserFieldInput(UserFieldGet):
    _tag = 'text:user-field-input'

Ancestors (in MRO)

Static methods

def __init__(

self, name=None, value=None, value_type=None, text=None, style=None, **kw)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self,
             name=None,
             value=None,
             value_type=None,
             text=None,
             style=None,
             **kw):
    super().__init__(**kw)
    if self._do_init:
        if name:
            self.name = name
        text = _set_value_and_type(
            self, value=value, value_type=value_type, text=text)
        self.text = text
        if style:
            self.style = style

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

Inheritance: UserFieldGet.attributes

var children

var clone

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var name

Get /set the attribute text:name

var parent

var root

var style

Get /set the attribute style:data-style-name

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class VarChapter

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class VarChapter(Element):
    _tag = 'text:chapter'
    _properties = (('display', 'text:display'), ('outline_level',
                                                 'text:outline-level'))
    display_value_choice = {
        'number', 'name', 'number-and-name', 'plain-number',
        'plain-number-and-name'
    }

    def __init__(self, display='name', outline_level=None, **kw):
        """display can be: 'number', 'name', 'number-and-name', 'plain-number' or
                           'plain-number-and-name'
        """
        super().__init__(**kw)
        if self._do_init:
            if display not in VarChapter.display_value_choice:
                raise ValueError("unknown display value: %s" % display)
            self.display = display
            if outline_level is not None:
                self.outline_level = outline_level

Ancestors (in MRO)

  • VarChapter
  • odfdo.element.Element
  • builtins.object

Class variables

var display_value_choice

Static methods

def __init__(

self, display='name', outline_level=None, **kw)

display can be: 'number', 'name', 'number-and-name', 'plain-number' or 'plain-number-and-name'

def __init__(self, display='name', outline_level=None, **kw):
    """display can be: 'number', 'name', 'number-and-name', 'plain-number' or
                       'plain-number-and-name'
    """
    super().__init__(**kw)
    if self._do_init:
        if display not in VarChapter.display_value_choice:
            raise ValueError("unknown display value: %s" % display)
        self.display = display
        if outline_level is not None:
            self.outline_level = outline_level

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

var children

var clone

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var display

Get /set the attribute text:display

var document_body

Return the document body : 'office:body'

var outline_level

Get /set the attribute text:outline-level

var parent

var root

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class VarCreationDate

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class VarCreationDate(Element):
    _tag = 'text:creation-date'
    _properties = (('fixed', 'text:fixed'), ('data_style',
                                             'style:data-style-name'))

    def __init__(self, fixed=False, data_style=None, **kw):
        super().__init__(**kw)
        if self._do_init:
            if fixed:
                self.fixed = True
            if data_style:
                self.data_style = data_style

Ancestors (in MRO)

Static methods

def __init__(

self, fixed=False, data_style=None, **kw)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self, fixed=False, data_style=None, **kw):
    super().__init__(**kw)
    if self._do_init:
        if fixed:
            self.fixed = True
        if data_style:
            self.data_style = data_style

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

var children

var clone

var data_style

Get /set the attribute style:data-style-name

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var fixed

Get /set the attribute text:fixed

var parent

var root

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class VarCreationTime

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class VarCreationTime(Element):
    _tag = 'text:creation-time'
    _properties = (('fixed', 'text:fixed'), ('data_style',
                                             'style:data-style-name'))

    def __init__(self, fixed=False, data_style=None, **kw):
        super().__init__(**kw)
        if self._do_init:
            if fixed:
                self.fixed = True
            if data_style:
                self.data_style = data_style

Ancestors (in MRO)

Static methods

def __init__(

self, fixed=False, data_style=None, **kw)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self, fixed=False, data_style=None, **kw):
    super().__init__(**kw)
    if self._do_init:
        if fixed:
            self.fixed = True
        if data_style:
            self.data_style = data_style

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

var children

var clone

var data_style

Get /set the attribute style:data-style-name

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var fixed

Get /set the attribute text:fixed

var parent

var root

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class VarDate

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class VarDate(Element):
    _tag = 'text:date'
    _properties = (('date', 'text:date-value'), ('fixed', 'text:fixed'),
                   ('data_style', 'style:data-style-name'),
                   ('date_adjust', 'text:date-adjust'))

    def __init__(self,
                 date=None,
                 fixed=False,
                 data_style=None,
                 text=None,
                 date_adjust=None,
                 **kw):
        super().__init__(**kw)
        if self._do_init:
            self.date = DateTime.encode(date)
            if fixed:
                self.fixed = True
            if data_style is not None:
                self.data_style = data_style
            if text is None:
                text = Date.encode(date)
            self.text = text
            if date_adjust is not None:
                self.date_adjust = Duration.encode(date_adjust)

Ancestors (in MRO)

  • VarDate
  • odfdo.element.Element
  • builtins.object

Static methods

def __init__(

self, date=None, fixed=False, data_style=None, text=None, date_adjust=None, **kw)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self,
             date=None,
             fixed=False,
             data_style=None,
             text=None,
             date_adjust=None,
             **kw):
    super().__init__(**kw)
    if self._do_init:
        self.date = DateTime.encode(date)
        if fixed:
            self.fixed = True
        if data_style is not None:
            self.data_style = data_style
        if text is None:
            text = Date.encode(date)
        self.text = text
        if date_adjust is not None:
            self.date_adjust = Duration.encode(date_adjust)

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

var children

var clone

var data_style

Get /set the attribute style:data-style-name

var date

Get /set the attribute text:date-value

var date_adjust

Get /set the attribute text:date-adjust

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var fixed

Get /set the attribute text:fixed

var parent

var root

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class VarDecl

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class VarDecl(Element):
    _tag = 'text:variable-decl'
    _properties = (('name', 'text:name'), ('value_type', 'office:value-type'))

    def __init__(self, name=None, value_type=None, **kw):
        super().__init__(**kw)
        if self._do_init:
            if name:
                self.name = name
            if value_type:
                self.value_type = value_type

Ancestors (in MRO)

  • VarDecl
  • odfdo.element.Element
  • builtins.object

Static methods

def __init__(

self, name=None, value_type=None, **kw)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self, name=None, value_type=None, **kw):
    super().__init__(**kw)
    if self._do_init:
        if name:
            self.name = name
        if value_type:
            self.value_type = value_type

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

var children

var clone

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var name

Get /set the attribute text:name

var parent

var root

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

var value_type

Get /set the attribute office:value-type

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class VarDecls

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class VarDecls(Element):
    _tag = 'text:variable-decls'

Ancestors (in MRO)

  • VarDecls
  • odfdo.element.Element
  • builtins.object

Static methods

def __init__(

self, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self, **kwargs):
    tag_or_elem = kwargs.pop('tag_or_elem', None)
    if tag_or_elem is None:
        # Instance for newly created object: create new lxml element and
        # continue by subclass __init__
        # If the tag key word exists, make a custom element
        self._do_init = True
        tag = kwargs.pop('tag', self._tag)
        self.__element = self.make_etree_element(tag)
    else:
        # called with an existing lxml element, sould be a result of
        # from_tag() casting, do not execute the subclass __ini__
        if not isinstance(tag_or_elem, _Element):
            raise TypeError(
                '"%s" is not an element node' % type(tag_or_elem))
        self._do_init = False
        self.__element = tag_or_elem

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

var children

var clone

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var parent

var root

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class VarDescription

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class VarDescription(VarInitialCreator):
    _tag = 'text:description'

Ancestors (in MRO)

Static methods

def __init__(

self, fixed=False, **kw)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self, fixed=False, **kw):
    super().__init__(**kw)
    if self._do_init:
        if fixed:
            self.fixed = True

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

Inheritance: VarInitialCreator.attributes

var children

var clone

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var fixed

Get /set the attribute text:fixed

var parent

var root

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class VarFileName

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class VarFileName(Element):
    _tag = 'text:file-name'
    _properties = (('display', 'text:display'), ('fixed', 'text:fixed'))
    display_value_choice = {'full', 'path', 'name', 'name-and-extension'}

    def __init__(self, display='full', fixed=False, **kw):
        """display can be: 'full', 'path', 'name' or 'name-and-extension'
        """
        super().__init__(**kw)
        if self._do_init:
            if display not in VarFileName.display_value_choice:
                raise ValueError("unknown display value: %s" % display)
            self.display = display
            if fixed:
                self.fixed = True

Ancestors (in MRO)

Class variables

var display_value_choice

Static methods

def __init__(

self, display='full', fixed=False, **kw)

display can be: 'full', 'path', 'name' or 'name-and-extension'

def __init__(self, display='full', fixed=False, **kw):
    """display can be: 'full', 'path', 'name' or 'name-and-extension'
    """
    super().__init__(**kw)
    if self._do_init:
        if display not in VarFileName.display_value_choice:
            raise ValueError("unknown display value: %s" % display)
        self.display = display
        if fixed:
            self.fixed = True

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

var children

var clone

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var display

Get /set the attribute text:display

var document_body

Return the document body : 'office:body'

var fixed

Get /set the attribute text:fixed

var parent

var root

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class VarGet

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class VarGet(Element):
    _tag = 'text:variable-get'
    _properties = (('name', 'text:name'), ('style', 'style:data-style-name'))

    def __init__(self,
                 name=None,
                 value=None,
                 value_type=None,
                 text=None,
                 style=None,
                 **kw):
        super().__init__(**kw)
        if self._do_init:
            if name:
                self.name = name
            if style:
                self.style = style
            text = _set_value_and_type(
                self, value=value, value_type=value_type, text=text)
            self.text = text

Ancestors (in MRO)

  • VarGet
  • odfdo.element.Element
  • builtins.object

Static methods

def __init__(

self, name=None, value=None, value_type=None, text=None, style=None, **kw)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self,
             name=None,
             value=None,
             value_type=None,
             text=None,
             style=None,
             **kw):
    super().__init__(**kw)
    if self._do_init:
        if name:
            self.name = name
        if style:
            self.style = style
        text = _set_value_and_type(
            self, value=value, value_type=value_type, text=text)
        self.text = text

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

var children

var clone

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var name

Get /set the attribute text:name

var parent

var root

var style

Get /set the attribute style:data-style-name

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class VarInitialCreator

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class VarInitialCreator(Element):
    _tag = 'text:initial-creator'
    _properties = (('fixed', 'text:fixed'), )

    def __init__(self, fixed=False, **kw):
        super().__init__(**kw)
        if self._do_init:
            if fixed:
                self.fixed = True

Ancestors (in MRO)

Static methods

def __init__(

self, fixed=False, **kw)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self, fixed=False, **kw):
    super().__init__(**kw)
    if self._do_init:
        if fixed:
            self.fixed = True

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

var children

var clone

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var fixed

Get /set the attribute text:fixed

var parent

var root

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class VarKeywords

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class VarKeywords(VarInitialCreator):
    _tag = 'text:keywords'

Ancestors (in MRO)

Static methods

def __init__(

self, fixed=False, **kw)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self, fixed=False, **kw):
    super().__init__(**kw)
    if self._do_init:
        if fixed:
            self.fixed = True

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

Inheritance: VarInitialCreator.attributes

var children

var clone

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var fixed

Get /set the attribute text:fixed

var parent

var root

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class VarPageCount

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class VarPageCount(Element):
    _tag = 'text:page-count'

Ancestors (in MRO)

Static methods

def __init__(

self, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self, **kwargs):
    tag_or_elem = kwargs.pop('tag_or_elem', None)
    if tag_or_elem is None:
        # Instance for newly created object: create new lxml element and
        # continue by subclass __init__
        # If the tag key word exists, make a custom element
        self._do_init = True
        tag = kwargs.pop('tag', self._tag)
        self.__element = self.make_etree_element(tag)
    else:
        # called with an existing lxml element, sould be a result of
        # from_tag() casting, do not execute the subclass __ini__
        if not isinstance(tag_or_elem, _Element):
            raise TypeError(
                '"%s" is not an element node' % type(tag_or_elem))
        self._do_init = False
        self.__element = tag_or_elem

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

var children

var clone

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var parent

var root

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class VarPageNumber

select_page -- string in ('previous', 'current', 'next')

page_adjust -- int (to add or subtract to the page number)

class VarPageNumber(Element):
    """
    select_page -- string in ('previous', 'current', 'next')

    page_adjust -- int (to add or subtract to the page number)
    """
    _tag = 'text:page-number'
    _properties = (('select_page', 'text:select-page'), ('page_adjust',
                                                         'text:page-adjust'))

    def __init__(self, select_page=None, page_adjust=None, **kw):
        super().__init__(**kw)
        if self._do_init:
            if select_page is None:
                select_page = 'current'
            self.select_page = select_page
            if page_adjust is not None:
                self.page_adjust = page_adjust

Ancestors (in MRO)

Static methods

def __init__(

self, select_page=None, page_adjust=None, **kw)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self, select_page=None, page_adjust=None, **kw):
    super().__init__(**kw)
    if self._do_init:
        if select_page is None:
            select_page = 'current'
        self.select_page = select_page
        if page_adjust is not None:
            self.page_adjust = page_adjust

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

var children

var clone

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var page_adjust

Get /set the attribute text:page-adjust

var parent

var root

var select_page

Get /set the attribute text:select-page

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class VarSet

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class VarSet(Element):
    _tag = 'text:variable-set'
    _properties = (('name', 'text:name'), ('style', 'style:data-style-name'),
                   ('display', 'text:display'))

    def __init__(self,
                 name=None,
                 value=None,
                 value_type=None,
                 display=False,
                 text=None,
                 style=None,
                 **kw):
        super().__init__(**kw)
        if self._do_init:
            if name:
                self.name = name
            if style:
                self.style = style
            text = _set_value_and_type(
                self, value=value, value_type=value_type, text=text)
            if not display:
                self.display = 'none'
            else:
                self.text = text

Ancestors (in MRO)

  • VarSet
  • odfdo.element.Element
  • builtins.object

Static methods

def __init__(

self, name=None, value=None, value_type=None, display=False, text=None, style=None, **kw)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self,
             name=None,
             value=None,
             value_type=None,
             display=False,
             text=None,
             style=None,
             **kw):
    super().__init__(**kw)
    if self._do_init:
        if name:
            self.name = name
        if style:
            self.style = style
        text = _set_value_and_type(
            self, value=value, value_type=value_type, text=text)
        if not display:
            self.display = 'none'
        else:
            self.text = text

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

var children

var clone

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var display

Get /set the attribute text:display

var document_body

Return the document body : 'office:body'

var name

Get /set the attribute text:name

var parent

var root

var style

Get /set the attribute style:data-style-name

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class VarSubject

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class VarSubject(VarInitialCreator):
    _tag = 'text:subject'

Ancestors (in MRO)

Static methods

def __init__(

self, fixed=False, **kw)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self, fixed=False, **kw):
    super().__init__(**kw)
    if self._do_init:
        if fixed:
            self.fixed = True

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

Inheritance: VarInitialCreator.attributes

var children

var clone

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var fixed

Get /set the attribute text:fixed

var parent

var root

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class VarTime

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class VarTime(Element):
    _tag = 'text:time'
    _properties = (('time', 'text:time-value'), ('fixed', 'text:fixed'),
                   ('data_style', 'style:data-style-name'),
                   ('time_adjust', 'text:time-adjust'))

    def __init__(self,
                 time=None,
                 fixed=False,
                 data_style=None,
                 text=None,
                 time_adjust=None,
                 **kw):
        super().__init__(**kw)
        if self._do_init:
            self.time = DateTime.encode(time)
            if fixed:
                self.fixed = True
            if data_style is not None:
                self.data_style = data_style
            if text is None:
                text = time.strftime('%H:%M:%S')
            self.text = text
            if time_adjust is not None:
                self.date_adjust = Duration.encode(time_adjust)

Ancestors (in MRO)

  • VarTime
  • odfdo.element.Element
  • builtins.object

Static methods

def __init__(

self, time=None, fixed=False, data_style=None, text=None, time_adjust=None, **kw)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self,
             time=None,
             fixed=False,
             data_style=None,
             text=None,
             time_adjust=None,
             **kw):
    super().__init__(**kw)
    if self._do_init:
        self.time = DateTime.encode(time)
        if fixed:
            self.fixed = True
        if data_style is not None:
            self.data_style = data_style
        if text is None:
            text = time.strftime('%H:%M:%S')
        self.text = text
        if time_adjust is not None:
            self.date_adjust = Duration.encode(time_adjust)

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

var children

var clone

var data_style

Get /set the attribute style:data-style-name

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var fixed

Get /set the attribute text:fixed

var parent

var root

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

var time

Get /set the attribute text:time-value

var time_adjust

Get /set the attribute text:time-adjust

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element

class VarTitle

Super class of all ODF classes. Representation of an XML element. Abstraction of the XML library behind.

class VarTitle(VarInitialCreator):
    _tag = 'text:title'

Ancestors (in MRO)

Static methods

def __init__(

self, fixed=False, **kw)

Initialize self. See help(type(self)) for accurate signature.

def __init__(self, fixed=False, **kw):
    super().__init__(**kw)
    if self._do_init:
        if fixed:
            self.fixed = True

def append(

self, str_or_element)

Insert element or text in the last position.

def append(self, str_or_element):
    """Insert element or text in the last position.
    """
    current = self.__element
    # Unicode ?
    if isinstance(str_or_element, str):
        # Has children ?
        children = current.getchildren()
        if children:
            # Append to tail of the last child
            last_child = children[-1]
            text = last_child.tail
            text = text if text is not None else ""
            text += str_or_element
            last_child.tail = text
        else:
            # Append to text of the element
            text = current.text
            text = text if text is not None else ""
            text += str_or_element
            current.text = text
    elif isinstance(str_or_element, Element):
        current.append(str_or_element.__element)
    else:
        raise TypeError('Element or unicode expected, not "%s"' %
                        (type(str_or_element)))

def append_named_range(

self, named_range)

Append the named range to the spreadsheet, replacing existing named range of same name if any.

Arguments:

named_range --  NamedRange
def append_named_range(self, named_range):
    """Append the named range to the spreadsheet, replacing existing named
    range of same name if any.
    Arguments:
        named_range --  NamedRange
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_expressions = self.get_element('table:named-expressions')
    if not named_expressions:
        named_expressions = Element.from_tag('table:named-expressions')
        self.append(named_expressions)
    # exists ?
    current = named_expressions.get_element(
        'table:named-range[@table:name="%s"][1]' % named_range.name)
    if current:
        named_expressions.delete(current)
    named_expressions.append(named_range)

def clear(

self)

Remove text, children and attributes from the element.

def clear(self):
    """Remove text, children and attributes from the element.
    """
    self.__element.clear()
    if hasattr(self, '_tmap'):
        self._tmap = []
    if hasattr(self, '_cmap'):
        self._cmap = []
    if hasattr(self, '_rmap'):
        self._rmap = []
    if hasattr(self, '_indexes'):
        remember = False
        if '_rmap' in self._indexes:
            remember = True
        self._indexes = {}
        self._indexes['_cmap'] = {}
        self._indexes['_tmap'] = {}
        if remember:
            self._indexes['_rmap'] = {}

def del_attribute(

self, name)

def del_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    del element.attrib[name]

def delete(

self, child=None, keep_tail=True)

Delete the given element from the XML tree. If no element is given, "self" is deleted. The XML library may allow to continue to use an element now "orphan" as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Arguments:

child -- Element

keep_tail -- boolean (default to True), True for most usages.
def delete(self, child=None, keep_tail=True):
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.
    if keep_tail is True (default), the tail text is not erased.
    Arguments:
        child -- Element
        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            info = self.serialize()
            raise ValueError("cannot delete the root element\n%s" % info)
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = current.tail
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

def delete_named_range(

self, name)

Delete the Named Range of specified name from the spreadsheet.

Arguments:

name -- str
def delete_named_range(self, name):
    """Delete the Named Range of specified name from the spreadsheet.
    Arguments:
        name -- str
    """
    if self.tag != 'office:spreadsheet':
        raise ValueError(
            "Element is no 'office:spreadsheet' : %s" % self.tag)
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = self.get_element('table:named-expressions')
    element = named_expressions.__element
    children = len(element.getchildren())
    if not children:
        self.delete(named_expressions)

def elements_repeated_sequence(

self, xpath_instance, name)

def elements_repeated_sequence(self, xpath_instance, name):
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    element = self.__element
    sub_elements = xpath_instance(element)
    result = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(name)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            value = int(value)
        except:
            value = 1
        result.append((idx, max(value, 1)))
    return result

def extend(

self, odf_elements)

Fast append elements at the end of ourself using extend.

def extend(self, odf_elements):
    """Fast append elements at the end of ourself using extend.
    """
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

def get_annotation(

self, position=0, creator=None, start_date=None, end_date=None, content=None, name=None)

Return the annotation that matches the criteria.

Arguments:

position -- int

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

name -- str

Return: Annotation or None if not found

def get_annotation(self,
                   position=0,
                   creator=None,
                   start_date=None,
                   end_date=None,
                   content=None,
                   name=None):
    """Return the annotation that matches the criteria.
    Arguments:
        position -- int
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
        name -- str
    Return: Annotation or None if not found
    """
    if name is not None:
        return _get_element(
            self, 'descendant::office:annotation', 0, office_name=name)
    annotations = self.get_annotations(
        creator=creator,
        start_date=start_date,
        end_date=end_date,
        content=content)
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

def get_annotation_end(

self, position=0, name=None)

Return the annotation end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_annotation_end(self, position=0, name=None):
    """Return the annotation end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::office:annotation-end',
        position,
        office_name=name)

def get_annotation_ends(

self)

Return all the annotation ends.

Return: list of Element

def get_annotation_ends(self):
    """Return all the annotation ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::office:annotation-end')

def get_annotations(

self, creator=None, start_date=None, end_date=None, content=None)

Return all the annotations that match the criteria.

Arguments:

creator -- str

start_date -- date object

end_date -- date object

content -- str regex

Return: list of Annotation

def get_annotations(self,
                    creator=None,
                    start_date=None,
                    end_date=None,
                    content=None):
    """Return all the annotations that match the criteria.
    Arguments:
        creator -- str
        start_date -- date object
        end_date -- date object
        content -- str regex
    Return: list of Annotation
    """
    annotations = []
    for annotation in _get_elements(
            self, 'descendant::office:annotation', content=content):
        if (creator is not None and creator != annotation.dc_creator):
            continue
        date = annotation.dc_date
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)
    return annotations

def get_attribute(

self, name)

def get_attribute(self, name):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    value = element.get(name)
    if value is None:
        return None
    elif value in ('true', 'false'):
        return Boolean.decode(value)
    return str(value)

def get_attribute_integer(

self, name)

def get_attribute_integer(self, name):
    atr = self.get_attribute(name)
    if atr is None:
        return atr
    try:
        return int(atr)
    except ValueError:
        return None

def get_between(

self, tag1, tag2, as_text=False, clean=True, no_header=True)

Returns elements between tag1 and tag2, tag1 and tag2 shall be unique and having an id attribute. (WARN: buggy if tag1/tag2 defines a malformed odf xml.) If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, ...) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and without headers.

Implementation and standard retrictions: Only text:h and text:p sould be 'cut' by an insert tag, so inner parts of insert tags are:

- any text:h, text:p or sub tag of these

- some text, part of a parent text:h or text:p

Arguments:

tag1 -- Element

tag2 -- Element

as_text -- boolean

clean -- boolean

no_header -- boolean

Return: list of odf_paragraph or odf_header

def get_between(self,
                tag1,
                tag2,
                as_text=False,
                clean=True,
                no_header=True):
    """Returns elements between tag1 and tag2, tag1 and tag2 shall
    be unique and having an id attribute.
    (WARN: buggy if tag1/tag2 defines a malformed odf xml.)
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and without headers.
    Implementation and standard retrictions:
    Only text:h and text:p sould be 'cut' by an insert tag, so inner parts
    of insert tags are:
        - any text:h, text:p or sub tag of these
        - some text, part of a parent text:h or text:p
    Arguments:
        tag1 -- Element
        tag2 -- Element
        as_text -- boolean
        clean -- boolean
        no_header -- boolean
    Return: list of odf_paragraph or odf_header
    """
    inner = self._get_between_base(tag1, tag2)
    if clean:
        clean_tags = ('text:change', 'text:change-start',
                      'text:change-end', 'text:reference-mark',
                      'text:reference-mark-start',
                      'text:reference-mark-end')
        request_self = ' | '.join(['self::%s' % c for c in clean_tags])
        inner = [e for e in inner if not e.xpath(request_self)]
        request = ' | '.join(['descendant::%s' % c for c in clean_tags])
        for element in inner:
            to_del = element.xpath(request)
            for e in to_del:
                element.delete(e)
    if no_header:  # crude replace t:h by t:p
        new_inner = []
        for element in inner:
            if element.tag == 'text:h':
                children = element.children
                text = element.__element.text
                para = Element.from_tag('text:p')
                para.text = text
                for c in children:
                    para.append(c)
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return '\n'.join([e.get_formatted_text() for e in inner])
    else:
        return inner

def get_bookmark(

self, position=0, name=None)

Return the bookmark that matches the criteria.

Arguments:

position -- int

name -- str

Return: Bookmark or None if not found

def get_bookmark(self, position=0, name=None):
    """Return the bookmark that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Bookmark or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark', position, text_name=name)

def get_bookmark_end(

self, position=0, name=None)

Return the bookmark end that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_end(self, position=0, name=None):
    """Return the bookmark end that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-end', position, text_name=name)

def get_bookmark_ends(

self)

Return all the bookmark ends.

Return: list of Element

def get_bookmark_ends(self):
    """Return all the bookmark ends.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-end')

def get_bookmark_start(

self, position=0, name=None)

Return the bookmark start that matches the criteria.

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_bookmark_start(self, position=0, name=None):
    """Return the bookmark start that matches the criteria.
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:bookmark-start', position, text_name=name)

def get_bookmark_starts(

self)

Return all the bookmark starts.

Return: list of Element

def get_bookmark_starts(self):
    """Return all the bookmark starts.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark-start')

def get_bookmarks(

self)

Return all the bookmarks.

Return: list of Element

def get_bookmarks(self):
    """Return all the bookmarks.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:bookmark')

def get_changes_ids(

self)

Return a list of ids that refers to a change region in the tracked changes list.

def get_changes_ids(self):
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes
    xpath_query = 'descendant::text:change-start/@text:change-id'
    # Deletion changes
    xpath_query += ' | descendant::text:change/@text:change-id'
    return self.xpath(xpath_query)

def get_draw_connector(

self, position=0, id=None, content=None)

Return the draw connector that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_connector(self, position=0, id=None, content=None):
    """Return the draw connector that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:connector',
        position,
        draw_id=id,
        content=content)

def get_draw_connectors(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw connectors that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_connectors(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw connectors that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:connector',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_ellipse(

self, position=0, id=None, content=None)

Return the draw ellipse that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_ellipse(self, position=0, id=None, content=None):
    """Return the draw ellipse that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:ellipse',
        position,
        draw_id=id,
        content=content)

def get_draw_ellipses(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw ellipses that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_ellipses(self,
                      draw_style=None,
                      draw_text_style=None,
                      content=None):
    """Return all the draw ellipses that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:ellipse',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_group(

self, position=0, name=None, title=None, description=None, content=None)

def get_draw_group(self,
                   position=0,
                   name=None,
                   title=None,
                   description=None,
                   content=None):
    return _get_element(
        self,
        'descendant::draw:g',
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_groups(

self, title=None, description=None, content=None)

def get_draw_groups(self, title=None, description=None, content=None):
    return _get_elements(
        self,
        'descendant::draw:g',
        svg_title=title,
        svg_desc=description,
        content=content)

def get_draw_line(

self, position=0, id=None, content=None)

Return the draw line that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_line(self, position=0, id=None, content=None):
    """Return the draw line that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:line',
        position,
        draw_id=id,
        content=content)

def get_draw_lines(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw lines that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_lines(self,
                   draw_style=None,
                   draw_text_style=None,
                   content=None):
    """Return all the draw lines that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:line',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_draw_page(

self, position=0, name=None, content=None)

Return the draw page that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: DrawPage or None if not found

def get_draw_page(self, position=0, name=None, content=None):
    """Return the draw page that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: DrawPage or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:page',
        position,
        draw_name=name,
        content=content)

def get_draw_pages(

self, style=None, content=None)

Return all the draw pages that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of DrawPage

def get_draw_pages(self, style=None, content=None):
    """Return all the draw pages that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of DrawPage
    """
    return _get_elements(
        self, 'descendant::draw:page', draw_style=style, content=content)

def get_draw_rectangle(

self, position=0, id=None, content=None)

Return the draw rectangle that matches the criteria.

Arguments:

position -- int

id -- str

content -- str regex

Return: odf_shape or None if not found

def get_draw_rectangle(self, position=0, id=None, content=None):
    """Return the draw rectangle that matches the criteria.
    Arguments:
        position -- int
        id -- str
        content -- str regex
    Return: odf_shape or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:rect',
        position,
        draw_id=id,
        content=content)

def get_draw_rectangles(

self, draw_style=None, draw_text_style=None, content=None)

Return all the draw rectangles that match the criteria.

Arguments:

draw_style -- str

draw_text_style -- str

content -- str regex

Return: list of odf_shape

def get_draw_rectangles(self,
                        draw_style=None,
                        draw_text_style=None,
                        content=None):
    """Return all the draw rectangles that match the criteria.
    Arguments:
        draw_style -- str
        draw_text_style -- str
        content -- str regex
    Return: list of odf_shape
    """
    return _get_elements(
        self,
        'descendant::draw:rect',
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content)

def get_element(

self, xpath_query)

def get_element(self, xpath_query):
    element = self.__element
    result = element.xpath(
        "(%s)[1]" % xpath_query, namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

def get_elements(

self, xpath_query)

def get_elements(self, xpath_query):
    element = self.__element
    if isinstance(xpath_query, XPath):
        result = xpath_query(element)
    else:
        new_xpath_query = _find_query_in_cache(to_bytes(xpath_query))
        result = new_xpath_query(element)
    if hasattr(self, '_tmap'):
        if hasattr(self, '_rmap'):
            cache = (self._tmap, self._cmap, self._rmap)
        else:
            cache = (self._tmap, self._cmap)
    else:
        cache = None
    return [Element.from_tag_for_clone(e, cache) for e in result]

def get_formatted_text(

self, context)

This function must return a beautiful version of the text

def get_formatted_text(self, context):
    """This function must return a beautiful version of the text
    """
    return ''

def get_frame(

self, position=0, name=None, presentation_class=None, title=None, description=None, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

title -- str regex

description -- str regex

content -- str regex

Return: Frame or None if not found

def get_frame(self,
              position=0,
              name=None,
              presentation_class=None,
              title=None,
              description=None,
              content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        title -- str regex
        description -- str regex
        content -- str regex
    Return: Frame or None if not found
    """
    return _get_element(
        self,
        'descendant::draw:frame',
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_frames(

self, presentation_class=None, style=None, title=None, description=None, content=None)

Return all the frames that match the criteria.

Arguments:

style -- str

title -- str regex

description -- str regex

content -- str regex

Return: list of Frame

def get_frames(self,
               presentation_class=None,
               style=None,
               title=None,
               description=None,
               content=None):
    """Return all the frames that match the criteria.
    Arguments:
        style -- str
        title -- str regex
        description -- str regex
        content -- str regex
    Return: list of Frame
    """
    return _get_elements(
        self,
        'descendant::draw:frame',
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content)

def get_header(

self, position=0, outline_level=None, content=None)

Return the Header that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Header or None if not found

def get_header(self, position=0, outline_level=None, content=None):
    """Return the Header that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Header or None if not found
    """
    return _get_element(
        self,
        'descendant::text:h',
        position,
        outline_level=outline_level,
        content=content)

def get_headers(

self, style=None, outline_level=None, content=None)

Return all the Headers that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Header

def get_headers(self, style=None, outline_level=None, content=None):
    """Return all the Headers that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Header
    """
    return _get_elements(
        self,
        'descendant::text:h',
        text_style=style,
        outline_level=outline_level,
        content=content)

def get_image(

self, position=0, name=None, url=None, content=None)

Return the image matching the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_image(self, position=0, name=None, url=None, content=None):
    """Return the image matching the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = _get_element(
            self,
            'descendant::draw:frame',
            position=position,
            draw_name=name)
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element('draw:image')
    return _get_element(
        self, 'descendant::draw:image', position, url=url, content=content)

def get_images(

self, style=None, url=None, content=None)

Return all the images matching the criteria.

Arguments:

style -- str

url -- str regex

content -- str regex

Return: list of Element

def get_images(self, style=None, url=None, content=None):
    """Return all the images matching the criteria.
    Arguments:
        style -- str
        url -- str regex
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self,
        'descendant::draw:image',
        text_style=style,
        url=url,
        content=content)

Return the link that matches the criteria.

Arguments:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Return: Element or None if not found

Return all the links that match the criteria.

Arguments:

name -- str

title -- str

url -- str regex

content -- str regex

Return: list of Element

def get_list(

self, position=0, content=None)

Return the list that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: List or None if not found

def get_list(self, position=0, content=None):
    """Return the list that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: List or None if not found
    """
    return _get_element(
        self, 'descendant::text:list', position, content=content)

def get_lists(

self, style=None, content=None)

Return all the lists that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of List

def get_lists(self, style=None, content=None):
    """Return all the lists that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of List
    """
    return _get_elements(
        self, 'descendant::text:list', text_style=style, content=content)

def get_named_range(

self, name)

Return the named range of specified name, or None if not found.

Arguments:

name -- str

Return: NamedRange

def get_named_range(self, name):
    """Return the named range of specified name, or None if not found.
    Arguments:
        name -- str
    Return: NamedRange
    """
    named_range = self.get_elements(
        'descendant::table:named-expressions/table:named-range[@table:name="%s"][1]'
        % name)
    if named_range:
        return named_range[0]
    else:
        return None

def get_named_ranges(

self)

Return all the tables named ranges.

Return: list of odf_named_range

def get_named_ranges(self):
    """Return all the tables named ranges.
    Return: list of odf_named_range
    """
    named_ranges = self.get_elements(
        'descendant::table:named-expressions/table:named-range')
    return named_ranges

def get_note(

self, position=0, note_id=None, note_class=None, content=None)

Return the note that matches the criteria.

Arguments:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: Note or None if not found

def get_note(self, position=0, note_id=None, note_class=None,
             content=None):
    """Return the note that matches the criteria.
    Arguments:
        position -- int
        note_id -- str
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: Note or None if not found
    """
    return _get_element(
        self,
        'descendant::text:note',
        position,
        text_id=note_id,
        note_class=note_class,
        content=content)

def get_notes(

self, note_class=None, content=None)

Return all the notes that match the criteria.

Arguments:

note_class -- 'footnote' or 'endnote'

content -- str regex

Return: list of Note

def get_notes(self, note_class=None, content=None):
    """Return all the notes that match the criteria.
    Arguments:
        note_class -- 'footnote' or 'endnote'
        content -- str regex
    Return: list of Note
    """
    return _get_elements(
        self,
        'descendant::text:note',
        note_class=note_class,
        content=content)

def get_office_names(

self)

Return all the used office:name tags values of the element.

Return: list of unique str

def get_office_names(self):
    """Return all the used office:name tags values of the element.
    Return: list of unique str
    """
    name_xpath_query = _find_query_in_cache('//@office:name')
    names = name_xpath_query(self.__element)
    uniq_names = list(set(names))
    return uniq_names

def get_orphan_draw_connectors(

self)

Return a list of connectors which don't have any shape connected to them.

def get_orphan_draw_connectors(self):
    """Return a list of connectors which don't have any shape connected
    to them.
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute('draw:start-shape')
        end_shape = connector.get_attribute('draw:end-shape')
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

def get_paragraph(

self, position=0, content=None)

Return the paragraph that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Paragraph or None if not found

def get_paragraph(self, position=0, content=None):
    """Return the paragraph that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Paragraph or None if not found
    """
    return _get_element(
        self, 'descendant::text:p', position, content=content)

def get_paragraphs(

self, style=None, content=None)

Return all the paragraphs that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Paragraph

def get_paragraphs(self, style=None, content=None):
    """Return all the paragraphs that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Paragraph
    """
    return _get_elements(
        self, 'descendant::text:p', text_style=style, content=content)

def get_reference_mark(

self, position=0, name=None)

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark(self, position=0, name=None):
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    name = to_str(name)
    if name:
        request = (f'descendant::text:reference-mark-start'
                   f'[@text:name="{name}"] '
                   f'| descendant::text:reference-mark'
                   f'[@text:name="{name}"]')
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:reference-mark-start '
                   '| descendant::text:reference-mark')
        return _get_element(self, request, position)

def get_reference_mark_end(

self, position=0, name=None)

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_end(self, position=0, name=None):
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-end',
        position,
        text_name=name)

def get_reference_mark_ends(

self)

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_ends(self):
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-end')

def get_reference_mark_single(

self, position=0, name=None)

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_single(self, position=0, name=None):
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:reference-mark', position, text_name=name)

def get_reference_mark_start(

self, position=0, name=None)

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Arguments:

position -- int

name -- str

Return: Element or None if not found

def get_reference_mark_start(self, position=0, name=None):
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()
    Arguments:
        position -- int
        name -- str
    Return: Element or None if not found
    """
    return _get_element(
        self,
        'descendant::text:reference-mark-start',
        position,
        text_name=name)

def get_reference_mark_starts(

self)

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Return: list of Element

def get_reference_mark_starts(self):
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark-start')

def get_reference_marks(

self)

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark-start).

Return: list of Element

def get_reference_marks(self):
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference
    (text:reference-mark-start).
    Return: list of Element
    """
    request = ('descendant::text:reference-mark-start '
               '| descendant::text:reference-mark')
    return _get_elements(self, request)

def get_reference_marks_single(

self)

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Return: list of Element

def get_reference_marks_single(self):
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:reference-mark')

def get_references(

self, name=None)

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Return: list of Element

Arguments:

name -- str or None
def get_references(self, name=None):
    """Return all the references (text:reference-ref). If name is
    provided, returns the references of that name.
    Return: list of Element
    Arguments:
        name -- str or None
    """
    if name is None:
        return _get_elements(self, 'descendant::text:reference-ref')
    request = 'descendant::text:reference-ref[@text:ref-name="%s"]' % to_bytes(
        name)
    return _get_elements(self, request)

def get_section(

self, position=0, content=None)

Return the section that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Element or None if not found

def get_section(self, position=0, content=None):
    """Return the section that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:section', position, content=content)

def get_sections(

self, style=None, content=None)

Return all the sections that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Element

def get_sections(self, style=None, content=None):
    """Return all the sections that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Element
    """
    return _get_elements(
        self, 'text:section', text_style=style, content=content)

def get_span(

self, position=0, content=None)

Return the span that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: Span or None if not found

def get_span(self, position=0, content=None):
    """Return the span that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: Span or None if not found
    """
    return _get_element(
        self, 'descendant::text:span', position, content=content)

def get_spans(

self, style=None, content=None)

Return all the spans that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Span

def get_spans(self, style=None, content=None):
    """Return all the spans that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Span
    """
    return _get_elements(
        self, 'descendant::text:span', text_style=style, content=content)

def get_style(

self, family, name_or_element=None, display_name=None)

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Arguments:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Return: odf_style or None if not found

def get_style(self, family, name_or_element=None, display_name=None):
    """Return the style uniquely identified by the family/name pair. If
    the argument is already a style object, it will return it.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.
    Arguments:
        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'
        name_or_element -- str or Style
        display_name -- str
    Return: odf_style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute('style:name')
        if name is not None:
            return name_or_element
        else:
            raise ValueError('Not a odf_style ?  %s' % name_or_element)
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    return _get_element(
        self,
        tagname,
        0,
        style_name=style_name,
        display_name=display_name,
        family=family)

def get_styled_elements(

self, name='')

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Arguments:

name -- str

Return: list

def get_styled_elements(self, name=''):
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).
    Arguments:
        name -- str
    Return: list
    """
    # FIXME incomplete (and possibly inaccurate)
    return (_get_elements(self, 'descendant::*', text_style=name) +
            _get_elements(self, 'descendant::*', draw_style=name) +
            _get_elements(self, 'descendant::*', draw_text_style=name) +
            _get_elements(self, 'descendant::*', table_style=name) +
            _get_elements(self, 'descendant::*', page_layout=name) +
            _get_elements(self, 'descendant::*', master_page=name) +
            _get_elements(self, 'descendant::*', parent_style=name))

def get_styles(

self, family=None)

def get_styles(self, family=None):
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return _get_elements(self, tagname, family=family)

def get_table(

self, position=0, name=None, content=None)

Return the table that matches the criteria.

Arguments:

position -- int

name -- str

content -- str regex

Return: Table or None if not found

def get_table(self, position=0, name=None, content=None):
    """Return the table that matches the criteria.
    Arguments:
        position -- int
        name -- str
        content -- str regex
    Return: Table or None if not found
    """
    if name is None and content is None:
        result = self._get_element_idx('descendant::table:table', position)
    else:
        result = _get_element(
            self,
            'descendant::table:table',
            position,
            table_name=name,
            content=content)
    return result

def get_tables(

self, style=None, content=None)

Return all the tables that match the criteria.

Arguments:

style -- str

content -- str regex

Return: list of Table

def get_tables(self, style=None, content=None):
    """Return all the tables that match the criteria.
    Arguments:
        style -- str
        content -- str regex
    Return: list of Table
    """
    return _get_elements(
        self,
        'descendant::table:table',
        table_style=style,
        content=content)

def get_text_change(

self, position=0, idx=None)

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change(self, position=0, idx=None):
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    if idx:
        request = ('descendant::text:change-start[@text:change-id="%s"] '
                   '| descendant::text:change[@text:change-id="%s"]') % (
                       idx, idx)
        return _get_element(self, request, position=0)
    else:
        request = ('descendant::text:change-start '
                   '| descendant::text:change')
        return _get_element(self, request, position)

def get_text_change_deletion(

self, position=0, idx=None)

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_deletion(self, position=0, idx=None):
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change', position, change_id=idx)

def get_text_change_deletions(

self)

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Return: list of Element

def get_text_change_deletions(self):
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:text:change')

def get_text_change_end(

self, position=0, idx=None)

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_end(self, position=0, idx=None):
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-end', position, change_id=idx)

def get_text_change_ends(

self)

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Return: list of Element

def get_text_change_ends(self):
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-end')

def get_text_change_start(

self, position=0, idx=None)

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Arguments:

position -- int

idx -- str

Return: Element or None if not found

def get_text_change_start(self, position=0, idx=None):
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()
    Arguments:
        position -- int
        idx -- str
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:change-start', position, change_id=idx)

def get_text_change_starts(

self)

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Return: list of Element

def get_text_change_starts(self):
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:change-start')

def get_text_changes(

self)

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Return: list of Element

def get_text_changes(self):
    """Return all the text changes, either single deletion
    (text:change) or start of range of changes (text:change-start).
    Return: list of Element
    """
    request = ('descendant::text:change-start '
               '| descendant::text:change')
    return _get_elements(self, request)

def get_toc(

self, position=0, content=None)

Return the table of contents that matches the criteria.

Arguments:

position -- int

content -- str regex

Return: odf_toc or None if not found

def get_toc(self, position=0, content=None):
    """Return the table of contents that matches the criteria.
    Arguments:
        position -- int
        content -- str regex
    Return: odf_toc or None if not found
    """
    return _get_element(
        self, 'text:table-of-content', position, content=content)

def get_tocs(

self)

Return all the tables of contents.

Return: list of odf_toc

def get_tocs(self):
    """Return all the tables of contents.
    Return: list of odf_toc
    """
    return _get_elements(self, 'text:table-of-content')

def get_tracked_changes(

self)

Return the tracked-changes part in the text body.

def get_tracked_changes(self):
    """Return the tracked-changes part in the text body.
    """
    return self.get_element('//text:tracked-changes')

def get_user_defined(

self, name, position=0)

return the user defined declaration for the given name.

return: Element or none if not found

def get_user_defined(self, name, position=0):
    """return the user defined declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-defined', position, text_name=name)

def get_user_defined_list(

self)

Return all the user defined field declarations.

Return: list of Element

def get_user_defined_list(self):
    """Return all the user defined field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-defined')

def get_user_defined_value(

self, name, value_type=None)

Return the value of the given user defined field name.

Arguments:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Return: most appropriate Python type

def get_user_defined_value(self, name, value_type=None):
    """Return the value of the given user defined field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return get_value(user_defined, value_type)

def get_user_field_decl(

self, name, position=0)

return the user field declaration for the given name.

return: Element or none if not found

def get_user_field_decl(self, name, position=0):
    """return the user field declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:user-field-decl', position, text_name=name)

def get_user_field_decl_list(

self)

Return all the user field declarations.

Return: list of Element

def get_user_field_decl_list(self):
    """Return all the user field declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:user-field-decl')

def get_user_field_decls(

self)

Return the container for user field declarations. Created if not found.

Return: Element

def get_user_field_decls(self):
    """Return the container for user field declarations. Created if not
    found.
    Return: Element
    """
    user_field_decls = self.get_element('//text:user-field-decls')
    if user_field_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:user-field-decls'), FIRST_CHILD)
        user_field_decls = body.get_element('//text:user-field-decls')
    return user_field_decls

def get_user_field_value(

self, name, value_type=None)

Return the value of the given user field name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_user_field_value(self, name, value_type=None):
    """Return the value of the given user field name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return get_value(user_field_decl, value_type)

def get_variable_decl(

self, name, position=0)

return the variable declaration for the given name.

return: Element or none if not found

def get_variable_decl(self, name, position=0):
    """return the variable declaration for the given name.
    return: Element or none if not found
    """
    return _get_element(
        self, 'descendant::text:variable-decl', position, text_name=name)

def get_variable_decl_list(

self)

Return all the variable declarations.

Return: list of Element

def get_variable_decl_list(self):
    """Return all the variable declarations.
    Return: list of Element
    """
    return _get_elements(self, 'descendant::text:variable-decl')

def get_variable_decls(

self)

Return the container for variable declarations. Created if not found.

Return: Element

def get_variable_decls(self):
    """Return the container for variable declarations. Created if not
    found.
    Return: Element
    """
    variable_decls = self.get_element('//text:variable-decls')
    if variable_decls is None:
        body = self.document_body
        body.insert(Element.from_tag('text:variable-decls'), FIRST_CHILD)
        variable_decls = body.get_element('//text:variable-decls')
    return variable_decls

def get_variable_set(

self, name, position=-1)

Return the variable set for the given name (last one by default).

Arguments:

name -- str

position -- int

Return: Element or None if not found

def get_variable_set(self, name, position=-1):
    """Return the variable set for the given name (last one by default).
    Arguments:
        name -- str
        position -- int
    Return: Element or None if not found
    """
    return _get_element(
        self, 'descendant::text:variable-set', position, text_name=name)

def get_variable_set_value(

self, name, value_type=None)

Return the last value of the given variable name.

Arguments:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Return: most appropriate Python type

def get_variable_set_value(self, name, value_type=None):
    """Return the last value of the given variable name.
    Arguments:
        name -- str
        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic
    Return: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return get_value(variable_set, value_type)

def get_variable_sets(

self, name=None)

Return all the variable sets that match the criteria.

Arguments:

name -- str

Return: list of Element

def get_variable_sets(self, name=None):
    """Return all the variable sets that match the criteria.
    Arguments:
        name -- str
    Return: list of Element
    """
    return _get_elements(
        self, 'descendant::text:variable-set', text_name=name)

def index(

self, child)

Return the position of the child in this element.

Inspired by lxml

def index(self, child):
    """Return the position of the child in this element.
    Inspired by lxml
    """
    return self.__element.index(child.__element)

def insert(

self, element, xmlposition=None, position=None, start=False)

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If text start is True, insert the element before any existing text.

Position start at 0.

Arguments:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int
def insert(self, element, xmlposition=None, position=None, start=False):
    """Insert an element relatively to ourself.
    Insert either using DOM vocabulary or by numeric position.
    If text start is True, insert the element before any existing text.
    Position start at 0.
    Arguments:
        element -- Element
        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING
        start -- Boolean
        position -- int
    """
    child_tag = element.tag
    current = self.__element
    element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, element)
    elif xmlposition is LAST_CHILD:
        current.append(element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, element)
    else:
        raise ValueError("(xml)position must be defined")

def is_empty(

self)

Check if the element is empty : no text, no children, no tail

Return: Boolean

def is_empty(self):
    """Check if the element is empty : no text, no children, no tail
    Return: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if element.getchildren():
        return False
    return True

def make_etree_element(

tag)

@staticmethod
def make_etree_element(tag):
    if not isinstance(tag, (str, bytes)):
        raise TypeError("tag is not str or bytes: %s" % tag)
    tag = to_bytes(tag).strip()
    if not tag:
        raise ValueError("tag is empty")
    if b'<' not in tag:
        # Qualified name
        # XXX don't build the element from scratch or lxml will pollute with
        # repeated namespace declarations
        tag = b'<%s/>' % tag
    # XML fragment
    root = fromstring(ns_document_data % tag)
    return root[0]

def match(

self, pattern)

return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: bool

def match(self, pattern):
    """return True if the pattern is found one or more times anywhere in
    the text content of the element.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: bool
    """
    return self.search(pattern) is not None

def replace(

self, pattern, new=None)

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

Arguments:

pattern -- str

new -- str

Return: int

def replace(self, pattern, new=None):
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurences that would be replaced.
    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
        new -- str
    Return: int
    """
    if isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath('descendant::text()'):
        if new is None:
            count += len(cpattern.findall(text))
        else:
            new_text, number = cpattern.subn(new, text)
            container = text.parent
            if text.is_text():
                container.text = new_text
            else:
                container.tail = new_text
            count += number
    return count

def replace_element(

self, old_element, new_element)

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

def replace_element(self, old_element, new_element):
    """Replaces in place a sub element with the element passed as second
    argument.
    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

def search(

self, pattern)

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Arguments:

pattern -- str

Return: int or None

def search(self, pattern):
    """Return the first position of the pattern in the text content of
    the element, or None if not found.
    Python regular expression syntax applies.
    Arguments:
        pattern -- str
    Return: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

def serialize(

self, pretty=False, with_ns=False)

def serialize(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data

def serialize2(

self, pretty=False, with_ns=False)

def serialize2(self, pretty=False, with_ns=False):
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data = tostring(
        native, with_tail=False, pretty_print=pretty, encoding='unicode')
    if not with_ns:
        # Remove namespaces
        data = ns_stripper.sub('', data)
    return data + str(len(data))

def set_attribute(

self, name, value)

def set_attribute(self, name, value):
    element = self.__element
    uri, name = _decode_qname(name)
    if uri is not None:
        name = '{%s}%s' % (uri, name)
    if type(value) is bool:
        value = Boolean.encode(value)
    elif value is None:
        try:
            del element.attrib[name]
        except KeyError:
            pass
        return
    element.set(name, str(value))

def set_style_attribute(

self, name, value)

Shortcut to accept a style object as a value.

def set_style_attribute(self, name, value):
    """Shortcut to accept a style object as a value.
    """
    if isinstance(value, Element):
        value = value.name
    return self.set_attribute(name, value)

def strip_elements(

self, sub_elements)

Remove the tags of provided elements, keeping inner childs and text.

Return : the striped element.

Warning : no clone in sub_elements list.

Arguments:

sub_elements -- Element or list of Element
def strip_elements(self, sub_elements):
    """Remove the tags of provided elements, keeping inner childs and text.
    Return : the striped element.
    Warning : no clone in sub_elements list.
    Arguments:
        sub_elements -- Element or list of Element
    """
    if not sub_elements:
        return self
    if isinstance(sub_elements, Element):
        sub_elements = (sub_elements, )
    replacer = to_bytes(_get_lxml_tag('text:this-will-be-removed'))
    for element in sub_elements:
        element.__element.tag = replacer
    strip = ('text:this-will-be-removed', )
    return self.strip_tags(strip=strip, default=None)

def strip_tags(

self, strip=None, protect=None, default='text:p')

Remove the tags listed in strip, recursively, keeping inner childs and text. Tags listed in protect stop the removal one level depth. If the first level element is stripped, default is used to embed the content in the default element. If default is None and first level is striped, a list of text and children is returned. Return : the striped element.

strip_tags should be used by on purpose methods (strip_span ...) (Method name taken from lxml).

Arguments:

strip -- iterable list of str odf tags, or None

protect -- iterable list of str odf tags, or None

default -- str odf tag, or None

Return:

Element or list.
def strip_tags(self, strip=None, protect=None, default='text:p'):
    """Remove the tags listed in strip, recursively, keeping inner childs
    and text. Tags listed in protect stop the removal one level depth. If
    the first level element is stripped, default is used to embed the
    content in the default element. If default is None and first level is
    striped, a list of text and children is returned. Return : the striped
    element.
    strip_tags should be used by on purpose methods (strip_span ...)
    (Method name taken from lxml).
    Arguments:
        strip -- iterable list of str odf tags, or None
        protect -- iterable list of str odf tags, or None
        default -- str odf tag, or None
    Return:
        Element or list.
    """
    if not strip:
        return self
    if not protect:
        protect = ()
    protected = False
    element, modified = Element._strip_tags(self, strip, protect,
                                            protected)
    if modified:
        if type(element) == list and default:
            new = Element.from_tag(default)
            for content in element:
                if isinstance(content, Element):
                    new.append(content)
                else:
                    new.text = content
            element = new
    return element

def xpath(

self, xpath_query)

Apply XPath query to the element and its subtree. Return list of Element or Text instances translated from the nodes found.

def xpath(self, xpath_query):
    """Apply XPath query to the element and its subtree. Return list of
    Element or Text instances translated from the nodes found.
    """
    element = self.__element
    xpath_instance = _find_query_in_cache(xpath_query)
    elements = xpath_instance(element)
    result = []
    for obj in elements:
        if type(obj) in (_ElementStringResult, _ElementUnicodeResult):
            result.append(Text(obj))
        elif type(obj) is _Element:
            result.append(Element.from_tag(obj))
        else:
            result.append(obj)
    return result

Instance variables

var attributes

Inheritance: VarInitialCreator.attributes

var children

var clone

var dc_creator

Get dc:creator value.

Return: str (or None if inexistant)

var dc_date

Get the dc:date value.

Return: datetime (or None if inexistant)

var document_body

Return the document body : 'office:body'

var fixed

Get /set the attribute text:fixed

var parent

var root

var svg_description

var svg_title

var tag

Get /set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Arguments:

qname -- str (e.g. "text:span")

var tail

Get / set the text immediately following the element.

var text

Get / set the text content of the element.

var text_content

Get / set the text of the embedded paragraph, including embeded annotations, cells...

Set create a paragraph if missing

var text_recursive

Methods

def from_tag(

cls, tag_or_elem)

Element class and subclass factory. Turn an lxml Element or ODF string tag into an ODF XML Element from the relevant class.

Arguments:

tag_or_elem -- ODF str tag or lxml.Element

Return: Element (or subclass) instance

@classmethod
def from_tag(cls, tag_or_elem):
    """Element class and subclass factory. Turn an lxml Element or ODF
    string tag into an ODF XML Element from the relevant class.
    Arguments:
        tag_or_elem -- ODF str tag or lxml.Element
    Return: Element (or subclass) instance
    """
    if not isinstance(tag_or_elem, _Element):
        # assume the argument is a prefix:name tag
        tag_or_elem = cls.make_etree_element(tag_or_elem)
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    return klass(tag_or_elem=tag_or_elem)

def from_tag_for_clone(

cls, tag_or_elem, cache)

@classmethod
def from_tag_for_clone(cls, tag_or_elem, cache):
    tag = to_str(tag_or_elem.tag)
    klass = _class_registry.get(tag, cls)
    element = klass(tag_or_elem=tag_or_elem)
    if cache and element._caching:
        element._tmap = cache[0]
        element._cmap = cache[1]
        if len(cache) == 3:
            element._rmap = cache[2]
    return element